Home Range Module

Module for Home Range calculation.

Even though home range is a fuzzy concept with several competing definitions, and estimation methods, in the literature, in this package home range is defined as:

Area occupied by an individual in the course of some fixed time span.

Home range calculation follows the next pipeline:

1. Inputs are Movement objects that contain position history of all simulated individuals for some number of steps
2. Space is discretized using some resolution that only depends on the mean velocity of the simulation. See home_range_resolution() to see the functional relationship between mean velocity and space resolution
3. For each individual, all pixels in discretized space occupied by the individual are counted, and an array with all presence-absence information is calculated
4. Each individual is assigned the total area of discretized space occupied along its movement

class ollin.core.home_range.HomeRange(movement)

Home Range class for storing home range values.

Movement data is processed into a grid of shape [num_individuals, x, y], where x and y are the sizes of discretized space and where:

grid[i, x, y] = 1

means that the (x, y) pixel was occupied by the i-th individual.

movement

Movement – Underlying movement data.

grid

array – Array of shape [num_individuals, x, y] with presence-absence information.

resolution

float – Spatial resolution for space discretization.

home_ranges

array – Array of shape [num_individuals] holding the home range in Km^2 for each individual.

mean_home_range

float – Average home range.

plot(ax=None, figsize=(10, 10), include=None, n_individual=0, hr_cmap='Blues', **kwargs)

Plot home range.

Plots all pixels occupied by an individual in discretized space.

Home Range plotting adds the following optional components to the plot:

1. “home_range:

   If present in include list, all pixels occupied by some subset of individuals will be colored. Diferent colors will be chosen for different individuals based on some colormap.

All other components in the include list will be passed down to the Movement plotting method. See Movement.plot() for all plot components defined at that level.

Parameters:

• ax (matplotlib.axes.Axes, optional) – Axes object in which to plot detection information.
• figsize (list or tuple, optional) – Size of figure to create if no axes object was given.
• include (list or tuple, optional) – List of components to plot. Components list will be passed first to the Movement Data object to add the corresponding components. Then components corresponding to Movement included in the list will be plotted.
• n_individual (int or list or tuple or array or str, optional) – If int will plot the home range of the corresponding individual. If it will plot the home range of all individuals in list/tuple/array. Otherwise it must be n_idividual=’all’, in which case it will plot all home ranges.
• hr_cmap (str, optional) – Colormap to use for home ranges, see matplotlib.cm to see all options. Defaults to ‘Blues’.
• kwargs (dict, optional) – All other keyworded arguments will be passed to the Movement plotting method.

Returns:

ax – Returns axes for further plotting.

Return type:

matplotlib.axes.Axes

ollin.core.home_range.make_grid(array, range, resolution)

Make and return presence absence grid in discretized space.

Given an array of shape [num, steps, 2] which encodes individual positions at different time steps in a rectangular area of dimensions=range, and a resolution for space discretization, calculates an array of presence and absence data of shape [num, x, y], where:

array[i, x, y] = 1

means that the i-th individual passed though the (x, y) pixel at some point.

Parameters:

• array (array) – Array of shape [num, steps, 2] of individuals positions.
• range (tuple or list or array) – Two dimensions of rectangular arena.
• resolution (float) – Resolution of space discretization.

Returns:

grid – Array of shape [num, x, y] where x ~ range[0] / resolution and y ~ range[1] / resolution.

Return type:

array